{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 前言-学习本项目你可以获得什么\n",
    "- 理论学习：了解MCP Server的基础知识\n",
    "- 上手实操：入门MCP Server的使用方式\n",
    "- 上手实操：将AppBuilder组件转换为MCP Server tool，并在client中使用"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 1. 项目背景\n",
    "### 1.1 什么是MCP Server Tool\n",
    "[Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)是Anthropic推出的一个开放协议，提供了一种将 AI 模型连接到不同数据源和工具的标准化方式，可实现应用与外部数据源和工具之间的无缝集成。\n",
    "\n",
    "MCP基础架构由以下几部分组成：\n",
    "- MCP Hosts: 希望通过 MCP 访问数据的程序，例如 Claude Desktop、IDE 或 AI 工具\n",
    "- MCP Clients: 与服务器保持 1:1 连接的协议客户端\n",
    "- MCP Servers: 通过MCP协议公开特定功能的程序\n",
    "- Local Data Sources: MCP协议可以安全访问的本机文件、数据库、服务等\n",
    "- Remote Services: MCP Server可以访问的远程服务\n",
    "\n",
    "其中MCP Server包含以下几类：\n",
    "- Resources: 上下文和数据，供用户或人工智能模型使用\n",
    "- Prompts: 为用户提供模板化的消息和工作流程\n",
    "- Tools: AI模型调用的工具，使模型能够与外部系统交互，例如查询数据库、调用 API 或执行计算\n",
    "\n",
    "MCP Server Tools有以下特征：\n",
    "- 每个工具都由名称唯一标识，并包含描述其架构的元数据\n",
    "- 被设计为模型控制的，这意味着语言模型可以根据其上下文理解和用户的提示自动发现和调用工具\n",
    "\n",
    "MCP Server Tool 示例：\n",
    "- MCP quick-start server: [weather server](https://modelcontextprotocol.io/quickstart/server)\n",
    "- MCP example servers: [example servers](https://modelcontextprotocol.io/examples)\n",
    "\n",
    "\n",
    "### 1.2 什么是AppBuilder组件\n",
    "SDK提供了40+个源于百度生态的优质组件，列表可见[组件列表](https://cloud.baidu.com/doc/AppBuilder/s/Glqb6dfiz#3%E3%80%81%E5%BC%80%E9%80%9A%E7%BB%84%E4%BB%B6%E6%9C%8D%E5%8A%A1), 调用前需要申领[免费试用额度](https://console.bce.baidu.com/ai-engine/old/#/ai/ocr/overview/resource/list)\n",
    "\n",
    "目前支持转换为MCP Server Tool的组件包括：\n",
    "| 组件名称 | 组件描述 |\n",
    "| --- | --- |\n",
    "| AnimalRecognition | 动物识别，可用于识别一张图片，即对于输入的一张图片（可正常解码，且长宽比较合适），输出动物识别结果。 |\n",
    "| ImageUnderstand | 图像内容理解，输出理解图片后的文本信息。 |\n",
    "| Translation | 文本翻译组件，提供多种语言互译的在线文本翻译服务。支持术语定制功能，用户可对翻译结果进行干预，快速提高翻译质量。可广泛应用于移动端、PC网站、智能硬件等不同产品形态中，满足多领域、多场景的翻译需求。 |\n",
    "| GeneralOCR | 通用文字识别组件，支持多场景、多语种、高精度的文字识别服务，对图片全部文字内容进行检测识别。 |\n",
    "| StyleRewrite | 风格转写组件，可以基于生成式大模型对文本的风格进行改写。支持多种文本风格，包括营销、客服、直播、激励及教学话术。 |\n",
    "| HallucinationDetection | 幻觉检测，针对问答场景，检测答案中是否存在幻觉。 |\n",
    "| QRcodeOCR | 二维码识别，可对图片中的二维码、条形码进行检测和识别，返回存储的文字信息及其位置信息。 |\n",
    "| HandwriteOCR | 手写文字识别，图片中的手写中文、手写数字进行检测和识别，针对不规则的手写字体进行专项优化，识别准确率可达90%以上。 |\n",
    "| MixCardOCR | 身份证混贴识别，身份证混贴识别支持自动检测与识别身份证正反面在同一张图片上的场景，一次识别图片中身份证正反面所有字段。 |\n",
    "| TableOCR | 表格文字识别，可支持识别图片中的表格内容，返回各表格的表头表尾内容、单元格文字内容及其行列位置信息，全面覆盖各类表格样式，包括常规有线表格、无线表格、含合并单元格表格。同时，支持多表格内容识别。 |\n",
    "| Text2Image | 文生图（AI作画-高级版），基于文心大模型，可以根据用户输入的文本，自动创作不限定风格的图，为内容创作者提供灵感和高质量配图。 |\n",
    "| StyleWriting | 风格写作组件，是一款基于生成式大模型进行文本创作的工具，支持多种风格，包括B站、小红书等，适用于编写文案、广告等多种场景。 |\n",
    "| TreeMind | 树图，提供智能思维导图制作工具和丰富的模板，支持脑图、逻辑图、树形图、鱼骨图、组织架构图、时间轴、时间线等多种专业格式。 |\n",
    "| ASR | 短语音识别，可以将音频流实时识别为文字，并返回每句话的开始和结束时间，适用于手机语音输入、语音搜索、人机对话等语音交互场景。 |\n",
    "| ObjectRecognition | 通用物体和场景识别组件，可以识别超过10万类常见物体和场景，接口返回大类及细分类的名称。广泛适用于图像或视频内容分析、拍照识图等业务场景 |\n",
    "| SimilarQuestion | 相似问生成组件，可以基于输入的问题，挖掘出与该问题相关的类似问题。广泛用于客服、问答等场景。 |\n",
    "| OralQueryGeneration | 口语化Query生成组件，可以基于输入文本生成与文档内容相关的Query。可用于增强文档索引等场景。 |\n",
    "| PlantRecognition | 植物识别，即对于输入的一张图片（可正常解码，且长宽比较合适），输出植物识别结果。 |\n",
    "\n",
    "即实现在appbuilder.core.components.v2目录下的组件。后续会逐步支持将所有的组件转化为MCP Server Tool。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 2. 项目介绍-将AppBuilder组件转换为MCP Server Tool\n",
    "\n",
    "### 目标：\n",
    "\n",
    "在Cursor里自定义个人专属办公工具 —— 用户自己可将AppBuilder官方提供的“文本翻译-通用版”、“植物识别”等组件转化为MCP Server，在Cursor中作为自定义工具直接调用。\n",
    "\n",
    "### 为什么使用这个案例？\n",
    "\n",
    "- AppBuilder有很多优质的组件，可以在Claude客户端、Cursor中通过MCP的方式联动   \n",
    "- 通过这种模式，未来可以支持用户把自己在AB上开发的工作流/Agent集成到本地支持MCP协议的Client中直接使用    \n",
    "- MCP协议提供两种方式定义server：low-level server 和 FastMCP server。其中low-level是基础接口，FastMCP是高级封装，是 MCP 协议的核心接口。它处理连接管理、协议合规性和消息路由。   \n",
    "\n",
    "下面提供一个使用FastMCP定义自己的MCP Server Tool的简单示例：\n",
    "\n",
    "【第一步】安装AppBuilder的环境依赖，在python>=3.12环境中，执行以下命令。Python环境准备可以参考教程：https://cloud.baidu.com/article/3421098"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "!python3 -m pip install appbuilder-sdk -i https://mirrors.aliyun.com/pypi/simple/\n",
    "!python3 -m pip install mcp -i https://mirrors.aliyun.com/pypi/simple/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "【第二步】我们可以快速将 AppBuilder 中的官方组件“文本翻译-通用版”、“植物识别”转换为 MCP Server 工具，该文件我们命名为 server.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "\n",
    "\"\"\"server.py\"\"\"\n",
    "\n",
    "import os\n",
    "from appbuilder.mcp_server.server import MCPComponentServer\n",
    "from appbuilder.core.components.v2 import Translation, PlantRecognition\n",
    "\n",
    "#设置APPBUILDER_TOKEN\n",
    "os.environ['APPBUILDER_TOKEN'] = '你的APPBUILDER_TOKEN'\n",
    "\n",
    "# 定义server\n",
    "server = MCPComponentServer(name=\"AB Component Server\")\n",
    "\n",
    "# 初始化组件实例\n",
    "translation = Translation()\n",
    "plant_recognition = PlantRecognition()\n",
    "\n",
    "# 把组件作为tool添加到server\n",
    "server.add_component(translation)\n",
    "server.add_component(plant_recognition)\n",
    "\n",
    "# 启动server\n",
    "server.run()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "注意：请将secret_key替换为你的APPBUILDER_TOKEN，Token获取方式见文档：https://cloud.baidu.com/doc/AppBuilder/s/lm68r8e6i\n",
    "\n",
    "【第三步】在Cursor中配置自己的server：https://docs.cursor.com/context/model-context-protocol ，根据指引填写MCP配置文件，指向我们第二步中创建的server.py，配置MCP Server。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "json"
    }
   },
   "outputs": [],
   "source": [
    "\n",
    "{\n",
    "  \"mcpServers\": {\n",
    "    \"AB component\": {\n",
    "      \"command\": \"/abs/path/to/python\",  # python解释器的绝对路径\n",
    "      \"args\": [\n",
    "        \"/abs/path/to/server.py\"         # server.py的绝对路径\n",
    "      ]\n",
    "    }\n",
    "  }\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "python解释器的路径，可以在终端中输入以下命令进行查看:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "\n",
    "# mac / linux\n",
    "which python\n",
    "\n",
    "# windows\n",
    "where python"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "【第四步】配置完成后，我们刷新MCP Servers配置，这时候可看到在本地部署好的 AppBuilder 官方组件工具。\n",
    "\n",
    "![cursor server tool配置](./image/cursor_list_tool.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**效果展示**：\n",
    "\n",
    "【示例一】在Cursor的Chat对话框里，我们输入query"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "把“你好，中国”翻译成英文"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cursor识别需要调用的工具，并请求权限：\n",
    "![请求权限](./image/cursor_run_tool.jpg)\n",
    "\n",
    "点击\"Run tool\"执行工具。\n",
    "\n",
    "成功调用“文本翻译”工具，并展示组件的输入输出以及最终回复答案\n",
    "![调用工具](./image/cursor_call_translation_result.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "【示例二】输入query"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "shellscript"
    }
   },
   "outputs": [],
   "source": [
    "识别 https://img.dutenews.com/a/10001/202111/50120fcde5bb6f9c950758c6d77b656f.png 中的植物"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cursor能够成功调用“植物识别”工具，并展示组件的输入输出，最终回复答案“根据植物识别模型的分析结果，这张图片中的植物是杨树，识别的置信度为55.7%”。\n",
    "\n",
    "![调用植物识别工具](./image/cursor_call_plantrec.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "注：Cursor可能存在思考工具调用参数错误的幻觉，如在正确的调用参数之上再封装一层\"kwargs\"。我们已完成对该幻觉问题的兼容，功能将会在1.0.6版本中上线。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 4. 项目总结\n",
    "\n",
    "本项目主要：\n",
    "- 介绍了MCP协议及Server的概念和使用方式\n",
    "- 介绍了如何定义MCP Server tool\n",
    "- 如何将AppBuilder组件转换为MCP Server tool\n",
    "- 最后使用Claude客户端展示了AppBuilder组件作为MCP Server Tool的使用效果。"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
